This chapter describes the setup and basic use of the Installer Debugger.
What is the Installer Debugger
The Installer Debugger is a set of resources that can be included in any Installer 4.0 script file so scriptwriters can easily debug and test their scripts. While Installer 4.0 is running it is continuously sending the Installer Debugger information about what it is currently doing. The Installer Debugger transforms this into a human-readable form that is displayed to the user to be used to monitor the Installer’s actions.
The Installer Debugger is implemented using Installer 4.0’s Action Handler feature that is available in a debug version of Installer 4.0. The Installer Debugger will not be usable on shipping versions of Installer 4.0.
Setting up the Installer Debugger
There are two easy ways to begin using the Installer Debugger with your scripts. If you are using MPW Rez to compile your script, then all you need to do is include the “Installer Debugger.r” file in your script file. Otherwise, you can use ResEdit or other resource editor to paste the resources from the “Installer Debugger.rsrc” file into your script file.
Invoking the Installer Debugger
You can easily switch to the Installer Debugger and back to the Installer using several methods.
Switching to the debugger - Click in an Installer Debugger window
- Hold down the Option-Control keys together
Switching to the Installer - Click the Go button in the Main Window
- Click the Step button to go until the next Installer action occurs
- Click in the Installer window if not stepping
Installer Debugger Menu
The Wasabi menu allows you to access the features of the Installer Debugger, as well as control execution of the Installer.
Each menu item is described below.
Main Control Brings the Main Window to the front.
Heap Window Opens or brings the Heap Window to the front.
Rule Window Opens or brings the Rule Window to the front.
Virtual Window Opens or brings the Virtual Window to the front.
Log To File Turns logging to a file on or off. Logging is turned on if this item is checked.
Preferences Opens or brings the Preferences Window to the front.
Go Returns control to the Installer.
Step Returns control to the Installer until the next action that will be displayed in the Main Window. When this action happens the Installer Debugger takes control and brings its windows to the front.
Fire Rules Forces the Installer to evaluate the rules of the current interface mode. This is handy when testing your rule logic using the Rule Window or Virtual Window.
Dump Text Allows the user to save the current contents of the Main Window to a TEXT file.
Quit Asks the Installer to quit. The Installer will quit at the next available opportunity.
Main Window
This chapter describes the Main Window feature of the Installer Debugger.
The Main Window
The Main Window is always present while the Installer Debugger is running. The purpose of the Main Window is to display progress and error information while the Installer is running. The Main Window is shown below.
Message Area
The bottom part of the Main Window contains a simple text display and editor for recording the progress and error information gathered from the Installer. You can save the contents of the window to a file by clicking on the Save button, however you will only be able to actually save to the root of the volume.
NOTE
Because the Main Window text display is based on TextEdit, its contents is limited to 32K. When the contents comes close to the limit, text is discarded from the top. u
Main Window’s Show Menu
The Show menu allows you to control the which actions are displayed during execution. This helps speed up execution of the Installer while preventing you from being overloaded with progress information.
Each menu item is described below.
All Progress Info Displays all possible information. Overrides all other menu selections in the Show menu.
Frameworks Displays information describing each framework before it is to be executed. Occurs only when firing the rules.
Rules Displays information describing each rule and its result after it has been executed. Occurs only when firing the rules.
Rule Clauses Displays information describing each rule clause and its result after it has been executed. Occurs only when firing the rules.
Action Atoms Displays information describing each Action Atom executed and its result after it has been executed. Occurs after clicking Install or Remove.
File Progress Displays preflight information describing the action to be taken for each File Atom specified in the installation or removal. Occurs after clicking Install or Remove.
Resource Progress Displays preflight information describing the action to be taken for each Resource Atom specified in the installation or removal. Occurs after clicking Install or Remove.
Font Progress Displays preflight information describing the action to be taken for each Font Atom specified in the installation or removal. Occurs after clicking Install or Remove.
Folder Merge Displays preflight information describing the action to be taken for each Folder Merge Atom specified in the installation or removal. Occurs after clicking Install or Remove.
Resource Merge Displays preflight information describing the action to be taken for each Resource Merge Atom specified in the installation or removal. Occurs after clicking Install or Remove.
NOTE
The above filters do not affect what is displayed in any other Installer Debugger window. u
Preferences Window
This chapter describes the Preferences Window feature of the Installer Debugger.
The Preferences Window
The Preferences Window allows you to specify the defaults of certain settings in the Installer Debugger and Main Window.
Checked options will be selected by default the next time you launch the Installer.
Rule Window
This chapter describes the Rule Window feature of the Installer Debugger.
The Rule Window
The Rule Window is used to view and change the execution of Global, Easy and Custom rules. The window has three main sections, the rule execution area, the break list area and the current assertions list area. The Rule Window is shown below.
When the Installer windows are frontmost, clicking in the Installer Debugger window, or holding down the Option-Command keys gives control to the debugger. To continue in the Installer click the Go button.
Rule Execution Area
The rule execution area contains the Frameworks pop-up menu and the Rules pop-up menu, as well as the rule clause evaluation list immediately under them. As the rules are executed in the Installer the current framework and rule will be displayed in their pop-up menus. The rule clauses for the current rule are displayed in a scrolling list below.
Break List
The break list is used to specify rule clauses that can be automatically stopped at or automatically remapped to a specific value to modify rule execution.
Assertions List
The assertions list shows the currently set assertions.
Browsing Frameworks and Rules
While in the Rule Window all frameworks and rules can be browsed using the Frameworks and Rules pop-up menus.
Selecting another framework or rule from the pop-up menus displays the appropriate rule clause, but does not change execution. This is handy for finding and choosing rule clauses to add to the break list.
Watching Rule Execution
Viewing Rule Execution
Whenever the Rule Window is open all rule execution is shown in the window. Rules are executed when the Installer user chooses another target disk or folder, or they switch from another application back to the Installer.
An arrow at the left edge of the list points to the currently executing rule clause, as shown below.
The word at the right edge of the list tells you the result of the rule clause.
Stepping through Rule Execution
To enable stepping through each rule clause as it is executed, the scriptwriter must click the Step button before forcing the rules to be executed. To force the rules to be executed, select Fire Rules from the Wasabi menu. When the Step button in the Rule Window is pressed, the Installer Debugger will stop and give control to the Rule Window when the next rule clause is being executed by the Installer.
Breaking on a Specific Rule Clause
To stop on a specific rule clause without stepping through all preceding rule clauses, place the rule clause in the break list. This is easily done by finding and selecting (by clicking on the rule clause text) the rule clauses you wish to stop on, and choosing Add Rule Clause To Break List from the Rules menu. You can also double-click on the rule clause to add it to the Break List.
After clicking the Go button if any rule clause in the break list is executed the Installer Debugger will stop rule execution and bring the Installer Debugger to the front. A dot (•) is placed to the left of the rule clause that caused the break.
To disable breaking on a rule clause in the break list, choose Do Nothing from the pop-up menu at the right edge of the break list for the rule clause you wish to disable.
To delete a rule clause from the break list entirely, select the rule clause in the list and choose Delete Selected Item From Break List from the Rules menu, or press the delete key.
Breaking on Every Type of Rule Clause
To stop on every rule clause of a certain type, choose Break On Rule Clause and the rule clause type from the Rules menu.
The rule clause name will show in the break list preceded by the word “Every”.
Modifying Rule Execution
The Installer Debugger also allows the scriptwriter to change the result returned by certain rule clauses. This ability to change the rule clause results during rule execution provides the scriptwriter with an easy way to test difficult to reproduce conditions. There are two ways to change the rule clause, one way is manual and the other way is automatic.
Changing the Result of the Current Rule Clause
If you wish to change the result of the current rule clause being executed then use the pop-up menu at the right edge of the rule execution list. This change affects the current rule clause during this rule execution only.
In the example below, the current rule clause is checking to see if the Macintosh has at least 1Mb of physical memory installed.
To test the error case when a user’s Macintosh has less than 1Mb of memory you can “remap” the result to be false, and the Installer will contain with the next rule clause as if the rule clause actually returned a false result.
Remapping Rule Clause Results
When there is a need to always return a false or true result for a rule clause, then the rule clause can be placed in the break list with the appropriate remapping. This is handy for creating complex testing situations where many rule clauses must be remapped to different results.
To remap a rule clause in the break list choose either Remap to TRUE or Remap to FALSE from the pop-up menu at the right edge of the break list.
In the example above, the CheckMinMemory(1) rule clause will automatically return a false result each time the rules are executed. If you wish to break at and remap the same rule clause then add two separate entries of the rule clause to the break list.
Heap Window
This chapter describes the Heap Window feature of the Installer Debugger.
The Heap Window
The Heap Window allows you to watch memory usage during execution of the Installer.
NOTE
The Heap Window is only functional when running in 32-bit addressing mode. Not all menu items are implemented. u
Virtual Window
This chapter describes the Virtual Window feature of the Installer Debugger.
The Virtual Window
The Virtual Window can be used alone or in conjunction with the Rule Window to simulate a user environment other than the configuration of the machine on which the Installer is running. For example, suppose your product only runs machines with 7.0 and newer installed and a minimum of 4 MBs of RAM. Your script should contain logic that checks for these constraints and modifies your Easy Install message appropriately. Using the Virtual Window to simulate various user configurations, you can test this logic without having the actual hardware or software.
NOTE
The Virtual Window should never be used as a total replacement for testing on the actual user environment. Since the Virtual Window does not affect calls you make in user or rule functions, any software or hardware checks made within these functions will always see the actual environement. u
The Virtual Window provides control over four common environmental parameters that correspond to specific rule clauses, in addition to control over the value returned from any Gestalt selector. The Virtual Window shown below has been setup to simulate a Mac II with 2 MBs of RAM and a target System file version of 6.0.4.
Only those parameters that are currently checked will be remapped. To stop all remapping either uncheck all parameters or close the window. Since the Virtual Window gets the rule clause evaluation before the Rule Window does, you'll always see the remapped result in the Rule Window.
Remapping the Target System File Version
Enter the version number of the target System file. All CheckFileVersion rule clauses that reference a target file named “System” will return true or false based on the version number entered in the Virtual Window.
Remapping the Target System File Region
Enter the region code (country code) of the target System file. All CheckFileCountryCode rule clauses that reference a target file named “System” will return true or false based on the region code entered in the Virtual Window. Region codes are define in the MPW inferface file “Script.h”.
Remapping the Minimum Physical RAM Memory
Enter the number of MBs of physical RAM you wish your virtual machine to have. All CheckMinMemory rule clauses will return true or false based on the number of MBs entered in the Virtual Window. The number of MBs must be a whole number.
Remapping the Target Volume Size
Enter the size of the target volume in KBs. All CheckTgtVolSize rule clauses will return true or false based on the number of KBs entered in the Virtual Window. The size must be a whole number.
Remapping Gestalt Values
Choose Add Gestalt Selector from the Virtual menu to specify the remapped value of a Gestalt selector. The following dialog will appear.
Enter the selector type and the new remapped value and click OK to add it to the list of remapped Gestal selectors. If a CheckGestalt or CheckGestaltAttributes rule clause references a selector that has been remapped, it will return true or false based on the remapped value. To edit an existing remapped Gestalt selector, double-click the line or select and choose Modify Gestalt Selector Info from the Virtual menu. To stop a selector from being remapped, select the line and choose Delete Gestalt Selector from the Virtual menu.
Currently defined Gestalt selectors and result values are listed in the MPW interface file “GestaltEqu.h”. Several popular selectors are listed below:
gestaltQuickdrawVersion 'qd '
gestaltOriginalQD = 0x000, /* original 1-bit QD */
gestalt8BitQD = 0x100, /* 8-bit color QD */
gestalt32BitQD = 0x200, /* 32-bit color QD */
gestalt32BitQD11 = 0x210, /* 32-bit color QDv1.1 */
gestalt32BitQD12 = 0x220, /* 32-bit color QDv1.2 */
gestalt32BitQD13 = 0x230, /* 32-bit color QDv1.3 */
gestaltQuickdrawFeatures 'qdrw'
gestaltHasColor = 0, /* color quickdraw present */
gestaltHasDeepGWorlds = 1, /* GWorlds deeper than 1-bit */
gestaltHasDirectPixMaps = 2 /* PixMaps direct (16 or 32 bit) */
gestaltSysArchitecture 'sysa'
gestalt68k = 1, /* Motorola MC68k architecture */
gestaltPowerPC = 2, /* IBM PowerPC architecture */
gestaltProcessorType 'proc'
gestalt68000 = 1,
gestalt68010 = 2,
gestalt68020 = 3,
gestalt68030 = 4,
gestalt68040 = 5,
gestaltMachineType 'mach'
gestaltClassic = 1,
gestaltMacXL = 2,
gestaltMac512KE = 3,
gestaltMacPlus = 4,
gestaltMacSE = 5,
gestaltMacII = 6,
gestaltMacIIx = 7,
gestaltMacIIcx = 8,
gestaltMacSE030 = 9,
gestaltPortable = 10,
gestaltMacIIci = 11,
gestaltMacIIfx = 13,
gestaltMacClassic = 17,
gestaltMacIIsi = 18,
gestaltMacLC = 19
gestaltQuadra900 = 20,
gestaltPowerBook170 = 21,
gestaltQuadra700 = 22,
gestaltClassicII = 23,
gestaltPowerBook100 = 24,
gestaltPowerBook140 = 25,
gestaltQuadra950 = 26,
gestaltMacLCII = 37,
gestaltPowerBook145 = 54
NOTE
Rule functions are not affected by the Virtual Window. Therefore, if you call Gestalt directly from within your rule function you will get the actual value, not the remapped value entered in the Virtual Window. u